---
layout: docs
page_title: plugin register - Command
description: |-
  The "plugin register" command registers a new plugin in Vault's plugin
  catalog.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# plugin register

The `plugin register` command registers a new plugin in Vault's plugin catalog.
The plugin's type of "auth", "database", or "secret" must be included.

<Note>

To register an enterprise plugin, you must register with the extracted
`.zip` file, not the binary.
Refer to the [Enterprise plugins](/vault/docs/plugins/plugin-management#enterprise-plugins) section
of the plugin management page for Vault compatibility requirements.

</Note>

## Examples

Register a plugin binary:

```shell-session
$ vault plugin register \
    -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
    auth my-custom-plugin
Success! Registered plugin: my-custom-plugin
```

Register an extracted plugin `.zip` file:

Before registering Key Management secrets engine v0.16.0+ent for the linux/amd64 system that runs Vault Enterprise,
`vault-plugin-secrets-keymgmt_v0.16.0+ent_linux_amd64.zip` needs to be downloaded from
https://releases.hashicorp.com/vault-plugin-secrets-keymgmt and extracted to
`<plugin_directory>/vault-plugin-secrets-keymgmt_v0.16.0+ent_linux_amd64/`.

```shell-session
$ vault plugin register
    -version=0.16.0+ent \                      # version must match the plugin version on the releases page
    secret \
    vault-plugin-secrets-keymgmt               # name must match the plugin name on the releases page
Success! Registered plugin: vault-plugin-secrets-keymgmt
```

Register a plugin binary with custom args:

```shell-session
$ vault plugin register \
    -sha256=d3f0a8be02f6c074cf38c9c99d4d04c9c6466249 \
    -args=--with-glibc,--with-curl-bindings \
    auth my-custom-plugin
```

Register an extracted plugin `.zip` file with custom args:

```shell-session
$ vault plugin register
    -version=0.16.0+ent \                      # version must match the plugin version on the releases page
    -args=--with-glibc,--with-curl-bindings \
    secret \
    vault-plugin-secrets-keymgmt               # name must match the plugin name on the releases page
```

Use the `-download` flag with the full version and plugin
name to download and register an official plugin from
[HashiCorp releases page](https://releases.hashicorp.com/):

```shell-session
$ vault plugin register
    -download \
    -version=0.16.0+ent \
    secret \
    vault-plugin-secrets-keymgmt
```

## Usage

The following flags are available in addition to the [standard set of
flags](/vault/docs/commands) included on all commands.

### Output options

- `-format` `(string: "table")` - Print the output in the given format. Valid
  formats are "table", "json", or "yaml". This can also be specified via the
  `VAULT_FORMAT` environment variable.

### Command options

- `sha256` `(string: "")` – The SHA256 sum of a plugin binary or the OCI image.
  You must provide `sha256` to register a plugin binary, but you must leave
  `sha256` unset to register an extracted `.zip` file.

- `-args` `([]string: [])` - Argument to pass to the plugin when starting. This
  flag can be specified multiple times to specify multiple args.

- `-command` `(string: "")` - Specifies the command path used to execute the
  plugin relative to the plugin directory or OCI image directory. You must
  provide `command` to register a plugin binary. Vault ignores `command` when
  you register with an extracted `.zip` file as it already knows the associated run command.

- `-env` `([]string: [])` - Environment variables to set for the plugin when
  starting. This flag can be specified multiple times to specify multiple
  environment variables.

- `-oci_image` `(string: "")` - OCI image to run. If specified, setting `-command`,
  `-args`, and `-env` will update the container's entrypoint, args, and environment
  variables (append-only) respectively.

- `-runtime` `(string: "")` - Vault plugin runtime to use if `-oci_image` is
  specified.

- `-version` `(string: "")` - Semantic version of the plugin. Used as the tag
  when specifying `-oci_image`, but any leading 'v' will automatically be trimmed.
   You can omit version to register a plugin binary, but you must provide
   an explicit version to register an extracted `.zip` file.

- `-download` `(bool: false)` - <EnterpriseAlert inline="true" /> **( BETA )**
  Tells Vault to download the specified plugin from the
  [HashiCorp releases page](https://releases.hashicorp.com/). Automatic
  downloads only support secret and auth plugins with artifacts containing
  `metadata.json` and `metadata.json.sig`. To use automatic downloads, your
  network must permit HTTPS and TCP port 443 between all
  Vault cluster nodes and `releases.hashicorp.com`.
